身份驗證 ¶

身份驗證是驗證使用者身份的過程。它通常使用識別符（例如使用者名稱或電子郵件地址）和秘密令牌（例如密碼或存取令牌）來判斷使用者是否為其聲稱的身份。身份驗證是登入功能的基礎。

Yii 提供了一個身份驗證框架，將各種組件連接起來以支援登入。要使用此框架，您主要需要完成以下工作：

• 設定 user 應用程式組件；
• 建立一個實作 yii\web\IdentityInterface 介面的類別。

設定 yii\web\User ¶

user 應用程式組件管理使用者身份驗證狀態。它要求您指定一個身份類別，其中包含實際的身份驗證邏輯。在以下應用程式設定中，user 的身份類別被設定為 app\models\User，其實現方式將在下一小節中說明。

return [
    'components' => [
        'user' => [
            'identityClass' => 'app\models\User',
        ],
    ],
];

實作 yii\web\IdentityInterface ¶

身份類別必須實作 yii\web\IdentityInterface，其中包含以下方法：

• findIdentity()：它使用指定的使用者 ID 尋找身份類別的實例。當您需要透過會話維護登入狀態時，會使用此方法。
• findIdentityByAccessToken()：它使用指定的存取令牌尋找身份類別的實例。當您需要透過單一秘密令牌驗證使用者身份時（例如在無狀態 RESTful 應用程式中），會使用此方法。
• getId()：它傳回此身份實例所代表的使用者 ID。
• getAuthKey()：它傳回用於驗證會話和自動登入的金鑰（如果已啟用）。
• validateAuthKey()：它實作驗證身份驗證金鑰的邏輯。

如果不需要特定方法，您可以實作一個空方法體。例如，如果您的應用程式是純粹的無狀態 RESTful 應用程式，您只需要實作 findIdentityByAccessToken() 和 getId()，而將所有其他方法留空。或者，如果您的應用程式僅使用會話身份驗證，則您需要實作除了 findIdentityByAccessToken() 之外的所有方法。

在以下範例中，身份類別被實作為與 user 資料庫表相關聯的 Active Record 類別。

<?php

use yii\db\ActiveRecord;
use yii\web\IdentityInterface;

class User extends ActiveRecord implements IdentityInterface
{
    public static function tableName()
    {
        return 'user';
    }

    /**
     * Finds an identity by the given ID.
     *
     * @param string|int $id the ID to be looked for
     * @return IdentityInterface|null the identity object that matches the given ID.
     */
    public static function findIdentity($id)
    {
        return static::findOne($id);
    }

    /**
     * Finds an identity by the given token.
     *
     * @param string $token the token to be looked for
     * @return IdentityInterface|null the identity object that matches the given token.
     */
    public static function findIdentityByAccessToken($token, $type = null)
    {
        return static::findOne(['access_token' => $token]);
    }

    /**
     * @return int|string current user ID
     */
    public function getId()
    {
        return $this->id;
    }

    /**
     * @return string|null current user auth key
     */
    public function getAuthKey()
    {
        return $this->auth_key;
    }

    /**
     * @param string $authKey
     * @return bool|null if auth key is valid for current user
     */
    public function validateAuthKey($authKey)
    {
        return $this->getAuthKey() === $authKey;
    }
}

您可以使用以下程式碼為每個使用者產生一個身份驗證金鑰，然後將其儲存在 user 表中

class User extends ActiveRecord implements IdentityInterface
{
    ......

    public function beforeSave($insert)
    {
        if (parent::beforeSave($insert)) {
            if ($this->isNewRecord) {
                $this->auth_key = \Yii::$app->security->generateRandomString();
            }
            return true;
        }
        return false;
    }
}

注意：不要將 User 身份類別與 yii\web\User 混淆。前者是實作身份驗證邏輯的類別。它通常被實作為與某些用於儲存使用者憑證資訊的持久性儲存相關聯的 Active Record 類別。後者是一個應用程式組件類別，負責管理使用者身份驗證狀態。

使用 yii\web\User ¶

您主要從 user 應用程式組件的角度使用 yii\web\User。

您可以使用運算式 Yii::$app->user->identity 偵測目前使用者的身份。它傳回代表目前已登入使用者的身份類別的實例，如果目前使用者未通過身份驗證（表示訪客），則傳回 null。以下程式碼顯示如何從 yii\web\User 檢索其他與身份驗證相關的資訊。

// the current user identity. `null` if the user is not authenticated.
$identity = Yii::$app->user->identity;

// the ID of the current user. `null` if the user not authenticated.
$id = Yii::$app->user->id;

// whether the current user is a guest (not authenticated)
$isGuest = Yii::$app->user->isGuest;

要登入使用者，您可以使用以下程式碼：

// find a user identity with the specified username.
// note that you may want to check the password if needed
$identity = User::findOne(['username' => $username]);

// logs in the user
Yii::$app->user->login($identity);

yii\web\User::login() 方法將目前使用者的身份設定為 yii\web\User。如果會話已啟用，它將把身份保留在會話中，以便在整個會話期間維護使用者身份驗證狀態。如果已啟用基於 Cookie 的登入（即「記住我」登入），它還會將身份儲存在 Cookie 中，以便只要 Cookie 保持有效，就可以從 Cookie 中恢復使用者身份驗證狀態。

為了啟用基於 Cookie 的登入，您需要在應用程式設定中將 yii\web\User::$enableAutoLogin 設定為 true。您還需要在呼叫 yii\web\User::login() 方法時提供持續時間參數。

要登出使用者，只需呼叫：

Yii::$app->user->logout();

請注意，僅當會話已啟用時，登出使用者才有意義。該方法將從記憶體和會話中清除使用者身份驗證狀態。預設情況下，它也會銷毀所有使用者會話資料。如果您想保留會話資料，則應改為呼叫 Yii::$app->user->logout(false)。

身份驗證事件 ¶

yii\web\User 類別在登入和登出過程中引發一些事件。

• EVENT_BEFORE_LOGIN：在 yii\web\User::login() 的開始時引發。如果事件處理程序將事件物件的 isValid 屬性設定為 false，則登入過程將被取消。
• EVENT_AFTER_LOGIN：在成功登入後引發。
• EVENT_BEFORE_LOGOUT：在 yii\web\User::logout() 的開始時引發。如果事件處理程序將事件物件的 isValid 屬性設定為 false，則登出過程將被取消。
• EVENT_AFTER_LOGOUT：在成功登出後引發。

您可以回應這些事件來實作諸如登入稽核、線上使用者統計之類的功能。例如，在 EVENT_AFTER_LOGIN 的處理程序中，您可以將登入時間和 IP 位址記錄在 user 表中。